I'm not quite sure how much to document the calculation itself. It's documented in pretty good detail in the specs, but then I've also heard that people are struggling with this. so perhaps it would be useful to understand what people are struggling with.

@sandtreader You had covered this recently, is this helpful?

@nc6 Have you considered "upstreaming" these explanations to the formal specs?

I think this is a really good start.

I'm not quite sure how much to document the calculation itself.
I think all of it? I understand it already exists elsewhere, but if we want the blueprint to be a source of truth, it should be rather complete. Having duplicate information (at least this early in the process) is not a bad thing.

I've also heard that people are struggling with this. so perhaps it would be useful to understand what people are struggling with
I haven't been working on implementing reward calculation in any node myself, so better to ask Paul Clark and @KtorZ who I know have directly worked on this.

One thing that would be really useful (@Quantumplation just gave this feedback in a meeting we had), would be clear definitions of timings, specifically within the epoch boundary. Getting those a little wrong can have big consequences obviously, and it's a bit unclear in my opinion.

OOh, yes, timing of things "at" the epoch boundary is certainly an interesting topic!